% $Id: advectors.tex 204 2009-04-20 01:59:36Z jsibert $
%
% Author: David Fournier
% Copyright (c) 2008 Regents of the University of California
%
\X{init\_number\_vector}
\X{init\_bounded\_number\_vector}
\X{init\_vector\_vector}
\X{init\_bounded\_vector\_vector}
\X{init\_matrix\_vector}
\X{init\_bounded\_matrix\_vector}
This chapter introduces three new \ADM\ types. They are
the {\tt init\_number\_vector}, {\tt init\_vector\_vector}, 
{\tt init\_matrix\_vector}, and the bounded versions of these,
the {\tt init\_bounded\_number\_vector}, {\tt init\_bounded\_vector\_vector}, 
and {\tt init\_bounded\_matrix\_vector}.
To understand the usefullness of these objects consider an application
which has two {\tt init\_number} objects.
\beginexample
PARAMETER_SECTION
  init_bounded_number a1(0.2,1.0,1)
  init_bounded_number a2(-1.0,0.3,2)
\endexample 
\noindent This creates two bounded numbers with different
upper and lower bounds and becoming active in different phases
of the minimization.
Now however suppose that the number of numbers we wish to
have in the model depends on some integer read in at run time such as
\beginexample
DATA_SECTION
  init_int n
 //  ...

PARAMETER_SECTION
  // want to have n numbers
  init_bounded_number a1(0.2,1.0,1)
  init_bounded_number a2(-1.0,0.3,2)
  // ....
  init_bounded_number an(-4.0,-3.0,n)
\endexample 
\noindent the above code is a sketch of what we want to 
achieve. It can not be accomlished with that kind of coding
of course because at compile time we don't have the value for n,
and in any event if n is large this sort of coding is boring.
Dynamic arrays are the answer to this problem. One could try
the following
\beginexample
DATA_SECTION
  init_int n
 //  ...

PARAMETER_SECTION
  // want to have n numbers
  init_bounded_vector a(1,n,-1.0,1.0,1)
\endexample 
\noindent but this won't work because for an {\tt init\_bounded\_vector}
the bounds and the starting phase are the same for all components of
the vector. The {\tt init\_bounded\_number\_vector} class
is intended to solve this problem.
\beginexample
DATA_SECTION
  init_int n
 //  ...

PARAMETER_SECTION
  // need to create some vectors to hold the bounds and
  // phase numbers
 LOC_CALCS
  dvector lb(1,n); 
  dvector ub(1,n); 
  ivector ph(1,n); 
  // get the desired values into lb,ub,ph somehow 
  lb.fill_seqadd(1,0.5);
  ub.fill_seqadd(2,0.5);
  ph.fill_seqadd(1,1);
 END_CALCS
  init_bounded_number_vector a(1,n,lb,ub,ph)
\endexample 
\noindent Then {\tt a(1)} is an object of type
{\tt init\_bounded\_number} with bounds {\tt lb(1)} and 
{\tt ub(1)} and becoming active in phase {\tt ph(1)}. 
Any of these three fields can be replaced with a number or
integer if the bound or phase number is constant such as
\beginexample
  init_bounded_number_vector a(1,n,1.0,ub,2)
\endexample 
\noindent where the lower bound is {\tt 1.0} and the
phase number is {\tt 2}.


